Overview

This document explains how to use the UI system in your engine. The system provides automatic initialization, proper rendering order (UI before world), and supports image-based buttons and frames.

The UI system integrates seamlessly with your workspace:

• Auto-initialization: The Core constructor automatically initializes the UiSystem

• Rendering Order: UI elements render before world objects (appearing on top)

• Image Support: Buttons and Frames accept Texture2D images via constructors

• State Management: Built-in hover/press/click states for buttons

Core Components

No manual initialization needed - Core handles everything.

Workspace

Workspace manages both world objects and UI elements:

public class Workspace
{
    public List<GameObject> GameObjects { get; private set; }
    public List<UiElement> UiElements { get; private set; }

    // Add world objects
    public void Add(GameObject gameObject) { ... }

    // Add UI elements
    public void Add(UiElement uiElement) { ... }

    // Updates and renders UI before world
    public void RenderWorld() { ... }
}

UiSystem

UiSystem.cs is the central manager for all UI elements:

public class UiSystem
{
    public static UiSystem Instance { get; private set; }

    // Auto-initialized by Core
    public void AddElement(UiElement element) { ... }
    public void RemoveElement(UiElement element) { ... }
    public void Update(float deltaTime) { ... }
    public void Render() { ... }
    public void UpdateAndRender(float deltaTime) { ... }
}

UI Elements

All UI elements inherit from UiElement and implement Render().

public abstract class UiElement : Component
{
    public abstract void Render();
    public virtual void Update(float deltaTime) { }
    public virtual void OnClick() { }
}

Built-in UI Components

Button

Creates clickable buttons with hover/press effects:

// Basic button
var button = new Button("Start", new Vector2(100, 100), new Vector2(200, 50));
Workspace.Add(button);

// Button with background image
var texture = TextureLoader.Load("button.png");
var buttonImage = new Button("Submit", texture, new Vector2(100, 100), new Vector2(200, 50));
Workspace.Add(buttonImage);

// Button with hover/press images
var bg = TextureLoader.Load("button.png");
var hover = TextureLoader.Load("button_hover.png");
var press = TextureLoader.Load("button_pressed.png");
var hoverButton = new Button("Hover Me", bg, new Vector2(100, 100), new Vector2(200, 50))
{
    HoveredImage = hover,
    PressedImage = press
};
Workspace.Add(hoverButton);

// Click event handler
hoverButton.OnClick += () =>
{
    Console.WriteLine("Button was clicked!");
};

Button Properties:

• Position - Button position (screen coordinates)

• Size - Button dimensions

• Visible - Show/hide the button

• Layer - Rendering priority (higher = on top)

• IsHovered - Mouse hovering state

• IsPressed - Mouse pressed down state

• IsClicked - Click triggered (auto-reset by system)

• OnClick - Event fired when button is clicked

Frame

Creates container frames with optional images or borders:

// Basic frame
var frame = new Frame("MainFrame", new Vector2(0, 0), new Vector2(800, 600));
frame.BorderColor = Color.White;
Workspace.Add(frame);

// Frame with background image
var bg = TextureLoader.Load("panel.png");
var framePanel = new Frame(bg, new Vector2(0, 0), new Vector2(800, 600));
Workspace.Add(framePanel);

// Frame with border image
var border = TextureLoader.Load("panel_border.png");
var frameBorder = new Frame(border, new Vector2(100, 100), new Vector2(400, 300))
{
    BorderImage = border
};
Workspace.Add(frameBorder);

// Visible toggle
framePanel.Visible = false;  // Hide
framePanel.Visible = true;   // Show

Frame Properties:

• Position - Frame position (screen coordinates)

• Size - Frame dimensions

• Visible - Show/hide the frame

• Layer - Rendering priority

• BackgroundImage - Main content texture

• BorderImage - Border texture (overrides background)

• BorderColor - Color for solid color frames

• IsHovered - Mouse hovering state

Usage Example

// Create core (auto-initializes UI system)
var core = new Core(1920, 1080, "My Game");

// Create UI elements
var startButton = new Button("Start Game", texture, new Vector2(100, 50), new Vector2(300, 50))
{
    OnClick = () =>
    {
        Console.WriteLine("Game started!");
    }
};

var panel = new Frame("InfoPanel", backgroundTexture, new Vector2(100, 300), new Vector2(600, 400));
panel.Visible = true;

// Add to workspace
core.Workspace.Add(startButton);
core.Workspace.Add(panel);

// Run the game loop (Core handles all updates/renders automatically)
core.Run();

Rendering Flow

Each frame, the rendering occurs in this order:

1. UI System Update - Update all UI elements (hover state, click detection)
2. UI System Render - Render all UI elements (visible on top)
3. World Render - Render world objects sorted by layer

This ensures UI elements always appear in front of 3D world objects.